The 'rrule' npm package is a powerful library for working with recurrence rules as defined in the iCalendar RFC. It allows you to generate and manipulate recurring dates with a high degree of flexibility and precision.
Generating Recurrence Rules
This feature allows you to generate a set of recurring dates based on a specified rule. In this example, the rule generates dates that occur weekly on Mondays and Fridays, starting from January 1, 2023, and ending on June 1, 2023.
const { RRule } = require('rrule');
const rule = new RRule({
freq: RRule.WEEKLY,
interval: 1,
byweekday: [RRule.MO, RRule.FR],
dtstart: new Date(Date.UTC(2023, 0, 1, 10, 30)),
until: new Date(Date.UTC(2023, 5, 1))
});
console.log(rule.all());Parsing Recurrence Rules
This feature allows you to parse a recurrence rule from a string in the iCalendar format. The example demonstrates how to parse a rule string and generate the corresponding dates.
const { RRule } = require('rrule');
const ruleString = 'FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,FR;DTSTART=20230101T103000Z;UNTIL=20230601T000000Z';
const rule = RRule.fromString(ruleString);
console.log(rule.all());Converting Recurrence Rules to String
This feature allows you to convert a recurrence rule to its string representation in the iCalendar format. The example shows how to create a rule and then convert it to a string.
const { RRule } = require('rrule');
const rule = new RRule({
freq: RRule.WEEKLY,
interval: 1,
byweekday: [RRule.MO, RRule.FR],
dtstart: new Date(Date.UTC(2023, 0, 1, 10, 30)),
until: new Date(Date.UTC(2023, 5, 1))
});
console.log(rule.toString());Handling Timezones
This feature allows you to handle timezones when working with recurrence rules. The example demonstrates how to create a rule and add it to a rule set, which can then be used to generate dates considering timezones.
const { RRule, RRuleSet, rrulestr } = require('rrule');
const rule = new RRule({
freq: RRule.WEEKLY,
interval: 1,
byweekday: [RRule.MO, RRule.FR],
dtstart: new Date(Date.UTC(2023, 0, 1, 10, 30)),
until: new Date(Date.UTC(2023, 5, 1))
});
const ruleSet = new RRuleSet();
ruleSet.rrule(rule);
console.log(ruleSet.all());The 'moment-recur' package extends the Moment.js library to support recurring dates. It is less feature-rich compared to 'rrule' but integrates well with Moment.js for simpler use cases.
The 'later' package is a flexible library for defining recurring schedules and executing functions at specified times. It offers more complex scheduling options but is less focused on iCalendar standards compared to 'rrule'.
The 'date-fns' package provides a wide range of date utility functions, including some support for recurring dates. It is more general-purpose and less specialized in recurrence rules compared to 'rrule'.
Library for working with recurrence rules for calendar dates.
rrule.js supports recurrence rules as defined in the iCalendar
RFC, with a few important
differences. It is a partial port of the
rrule module from the excellent
python-dateutil library. On top of
that, it supports parsing and serialization of recurrence rules from and
to natural language.
gh-pages branch$ yarn add rrule
Includes optional TypeScript types
$ yarn add rrule
# or
$ npm install rrule
RRule:
import { datetime, RRule, RRuleSet, rrulestr } from 'rrule'
// Create a rule:
const rule = new RRule({
freq: RRule.WEEKLY,
interval: 5,
byweekday: [RRule.MO, RRule.FR],
dtstart: datetime(2012, 2, 1, 10, 30),
until: datetime(2012, 12, 31)
})
// Get all occurrence dates (Date instances):
rule.all()
[ '2012-02-03T10:30:00.000Z',
'2012-03-05T10:30:00.000Z',
'2012-03-09T10:30:00.000Z',
'2012-04-09T10:30:00.000Z',
'2012-04-13T10:30:00.000Z',
'2012-05-14T10:30:00.000Z',
'2012-05-18T10:30:00.000Z',
/* … */]
// Get a slice:
rule.between(datetime(2012, 8, 1), datetime(2012, 9, 1))
['2012-08-27T10:30:00.000Z',
'2012-08-31T10:30:00.000Z']
// Get an iCalendar RRULE string representation:
// The output can be used with RRule.fromString().
rule.toString()
"DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;INTERVAL=5;UNTIL=20130130T230000Z;BYDAY=MO,FR"
// Get a human-friendly text representation:
// The output can be used with RRule.fromText().
rule.toText()
"every 5 weeks on Monday, Friday until January 31, 2013"
RRuleSet:
const rruleSet = new RRuleSet()
// Add a rrule to rruleSet
rruleSet.rrule(
new RRule({
freq: RRule.MONTHLY,
count: 5,
dtstart: datetime(2012, 2, 1, 10, 30),
})
)
// Add a date to rruleSet
rruleSet.rdate(datetime(2012, 7, 1, 10, 30))
// Add another date to rruleSet
rruleSet.rdate(datetime(2012, 7, 2, 10, 30))
// Add a exclusion rrule to rruleSet
rruleSet.exrule(
new RRule({
freq: RRule.MONTHLY,
count: 2,
dtstart: datetime(2012, 3, 1, 10, 30),
})
)
// Add a exclusion date to rruleSet
rruleSet.exdate(datetime(2012, 5, 1, 10, 30))
// Get all occurrence dates (Date instances):
rruleSet.all()[
('2012-02-01T10:30:00.000Z',
'2012-05-01T10:30:00.000Z',
'2012-07-01T10:30:00.000Z',
'2012-07-02T10:30:00.000Z')
]
// Get a slice:
rruleSet.between(datetime(2012, 2, 1), datetime(2012, 6, 2))[
('2012-05-01T10:30:00.000Z', '2012-07-01T10:30:00.000Z')
]
// To string
rruleSet.valueOf()[
('DTSTART:20120201T023000Z',
'RRULE:FREQ=MONTHLY;COUNT=5',
'RDATE:20120701T023000Z,20120702T023000Z',
'EXRULE:FREQ=MONTHLY;COUNT=2',
'EXDATE:20120601T023000Z')
]
// To string
rruleSet.toString()
;('["DTSTART:20120201T023000Z","RRULE:FREQ=MONTHLY;COUNT=5","RDATE:20120701T023000Z,20120702T023000Z","EXRULE:FREQ=MONTHLY;COUNT=2","EXDATE:20120601T023000Z"]')
rrulestr:
// Parse a RRule string, return a RRule object
rrulestr('DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5')
// Parse a RRule string, return a RRuleSet object
rrulestr('DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5', {
forceset: true,
})
// Parse a RRuleSet string, return a RRuleSet object
rrulestr(
'DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5\nRDATE:20120701T023000Z,20120702T023000Z\nEXRULE:FREQ=MONTHLY;COUNT=2\nEXDATE:20120601T023000Z'
)
Dates in JavaScript are tricky. RRule tries to support as much flexibility as possible without adding any large required 3rd party dependencies, but that means we also have some special rules.
By default, RRule deals in "floating" times or UTC timezones. If you want results in a specific timezone, RRule also provides timezone support. Either way, JavaScript's built-in "timezone" offset tends to just get in the way, so this library simply doesn't use it at all. All times are returned with zero offset, as though it didn't exist in JavaScript.
THE BOTTOM LINE: Returned "UTC" dates are always meant to be interpreted as dates in your local timezone. This may mean you have to do additional conversion to get the "correct" local time with offset applied.
For this reason, it is highly recommended to use timestamps in UTC eg. new Date(Date.UTC(...)). Returned dates will likewise be in UTC (except on Chrome, which always returns dates with a timezone offset). It's recommended to use the provided datetime() helper, which
creates dates in the correct format using a 1-based month.
For example:
// local machine zone is America/Los_Angeles
const rule = RRule.fromString(
"DTSTART;TZID=America/Denver:20181101T190000;\n"
+ "RRULE:FREQ=WEEKLY;BYDAY=MO,WE,TH;INTERVAL=1;COUNT=3"
)
rule.all()
[ 2018-11-01T18:00:00.000Z,
2018-11-05T18:00:00.000Z,
2018-11-07T18:00:00.000Z ]
// Even though the given offset is `Z` (UTC), these are local times, not UTC times.
// Each of these this is the correct local Pacific time of each recurrence in
// America/Los_Angeles when it is 19:00 in America/Denver, including the DST shift.
// You can get the local components by using the getUTC* methods eg:
date.getUTCDate() // --> 1
date.getUTCHours() // --> 18
If you want to get the same times in true UTC, you may do so (e.g., using Luxon):
rule.all().map(date =>
DateTime.fromJSDate(date)
.toUTC()
.setZone('local', { keepLocalTime: true })
.toJSDate()
)
[ 2018-11-02T01:00:00.000Z,
2018-11-06T02:00:00.000Z,
2018-11-08T02:00:00.000Z ]
// These times are in true UTC; you can see the hours shift
For more examples see python-dateutil documentation.
Rrule also supports use of the TZID parameter in the
RFC using the
Intl API.
Support matrix for the Intl API applies. If you need to support additional environments,
please consider using a polyfill.
Example with TZID:
new RRule({
dtstart: datetime(2018, 2, 1, 10, 30),
count: 1,
tzid: 'Asia/Tokyo',
}).all()[
// assuming the system timezone is set to America/Los_Angeles, you get:
'2018-01-31T17:30:00.000Z'
]
// which is the time in Los Angeles when it's 2018-02-01T10:30:00 in Tokyo.
Whether or not you use the TZID param, make sure to only use JS Date objects that are
represented in UTC to avoid unexpected timezone offsets being applied, for example:
// WRONG: Will produce dates with TZ offsets added
new RRule({
freq: RRule.MONTHLY,
dtstart: new Date(2018, 1, 1, 10, 30),
until: new Date(2018, 2, 31),
}).all()[('2018-02-01T18:30:00.000Z', '2018-03-01T18:30:00.000Z')]
// RIGHT: Will produce dates with recurrences at the correct time
new RRule({
freq: RRule.MONTHLY,
dtstart: datetime(2018, 2, 1, 10, 30),
until: datetime(2018, 3, 31),
}).all()[('2018-02-01T10:30:00.000Z', '2018-03-01T10:30:00.000Z')]
RRule Constructornew RRule(options[, noCache=false])
The options argument mostly corresponds to the properties defined for RRULE in the
iCalendar RFC. Only freq is required.
| Option | Description |
|---|---|
freq |
(required) One of the following constants:
|
dtstart | The recurrence start. Besides being the base for the
recurrence, missing parameters in the final recurrence
instances will also be extracted from this date. If not
given, new Date will be used instead.
**IMPORTANT:** See the discussion under timezone support
|
interval | The interval between each freq iteration. For example,
when using RRule.YEARLY, an interval of 2 means
once every
two years, but with RRule.HOURLY, it means once every two
hours.
The default interval is 1.
|
wkst | The week start day. Must be one of the RRule.MO,
RRule.TU, RRule.WE constants, or an integer,
specifying
the first day of the week. This will affect recurrences based
on weekly periods. The default week start is RRule.MO.
|
count | How many occurrences will be generated. |
until | If given, this must be a Date instance, that will specify
the limit of the recurrence. If a recurrence instance happens
to be the same as the Date instance given in the
until
argument, this will be the last occurrence.
|
tzid | If given, this must be a IANA string recognized by the Intl API. See discussion under Timezone support. |
bysetpos | If given, it must be either an integer, or an array of
integers, positive or negative. Each given integer will specify
an occurrence number, corresponding to the nth occurrence of
the rule inside the frequency period. For example, a
bysetpos of -1 if combined with a RRule.MONTHLY
frequency, and a byweekday of (RRule.MO, RRule.TU,
RRule.WE, RRule.TH, RRule.FR), will result in
the last
work day of every month.
|
bymonth | If given, it must be either an integer, or an array of integers, meaning the months to apply the recurrence to. |
bymonthday | If given, it must be either an integer, or an array of integers, meaning the month days to apply the recurrence to. |
byyearday | If given, it must be either an integer, or an array of integers, meaning the year days to apply the recurrence to. |
byweekno | If given, it must be either an integer, or an array of integers, meaning the week numbers to apply the recurrence to. Week numbers have the meaning described in ISO8601, that is, the first week of the year is that containing at least four days of the new year. |
byweekday | If given, it must be either an integer (0 == RRule.MO), an
array of integers, one of the weekday constants
(RRule.MO,
RRule.TU, etc), or an array of these constants. When
given,
these variables will define the weekdays where the recurrence
will be applied. It's also possible to use an argument n for
the weekday instances, which will mean the nth occurrence of
this weekday in the period. For example, with
RRule.MONTHLY,
or with RRule.YEARLY and BYMONTH, using
RRule.FR.nth(+1) or RRule.FR.nth(-1) in byweekday
will specify the first or last friday of the month where the
recurrence happens.
Notice
that the RFC documentation, this is specified as BYDAY,
but was renamed to avoid the ambiguity of that argument.
|
byhour | If given, it must be either an integer, or an array of integers, meaning the hours to apply the recurrence to. |
byminute | If given, it must be either an integer, or an array of integers, meaning the minutes to apply the recurrence to. |
bysecond | If given, it must be either an integer, or an array of integers, meaning the seconds to apply the recurrence to. |
byeaster | This is an extension to the RFC specification which the Python implementation provides. Not implemented in the JavaScript version. |
noCache: Set to true to disable caching of results. If you will use the
same rrule instance multiple times, enabling caching will improve the
performance considerably. Enabled by default.
See also python-dateutil documentation.
rule.optionswkstart). Currently,
rule.options.byweekday isn't equal
to rule.origOptions.byweekday (which is an inconsistency).
rule.origOptionsoptions argument passed to
the constructor.RRule.prototype.all([iterator])Returns all dates matching the rule. It is a replacement for the iterator protocol this class implements in the Python version.
As rules without until or count represent infinite date series, you
can optionally pass iterator, which is a function that is called for
each date matched by the rule. It gets two parameters date (the Date
instance being added), and i (zero-indexed position of date in the
result). Dates are being added to the result as long as the iterator
returns true. If a false-y value is returned, date isn't added to
the result and the iteration is interrupted (possibly prematurely).
rule.all()[
('2012-02-01T10:30:00.000Z',
'2012-05-01T10:30:00.000Z',
'2012-07-01T10:30:00.000Z',
'2012-07-02T10:30:00.000Z')
]
rule.all(function (date, i) {
return i < 2
})[('2012-02-01T10:30:00.000Z', '2012-05-01T10:30:00.000Z')]
RRule.prototype.between(after, before, inc=false [, iterator])Returns all the occurrences of the rrule between after and before.
The inc keyword defines what happens if after and/or before are
themselves occurrences. With inc == true, they will be included in the
list, if they are found in the recurrence set.
Optional iterator has the same function as it has with
RRule.prototype.all().
rule.between(datetime(2012, 8, 1), datetime(2012, 9, 1))[
('2012-08-27T10:30:00.000Z', '2012-08-31T10:30:00.000Z')
]
RRule.prototype.before(dt, inc=false)Returns the last recurrence before the given Date instance. The inc
argument defines what happens if dt is an occurrence. With
inc == true, if dt itself is an occurrence, it will be returned.
RRule.prototype.after(dt, inc=false)Returns the first recurrence
after the given Date instance. The inc argument defines what happens
if dt is an occurrence. With inc == true, if dt itself is an
occurrence, it will be returned.
See also python-dateutil documentation.
RRule.prototype.toString()Returns a string representation of the rule as per the iCalendar RFC.
Only properties explicitly specified in options are included:
rule.toString()
;('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;INTERVAL=5;UNTIL=20130130T230000Z;BYDAY=MO,FR')
rule.toString() == RRule.optionsToString(rule.origOptions)
true
RRule.optionsToString(options)Converts options to iCalendar RFC RRULE string:
// Get full a string representation of all options,
// including the default and inferred ones.
RRule.optionsToString(rule.options)
;('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;INTERVAL=5;WKST=0;UNTIL=20130130T230000Z;BYDAY=MO,FR;BYHOUR=10;BYMINUTE=30;BYSECOND=0')
// Cherry-pick only some options from an rrule:
RRule.optionsToString({
freq: rule.options.freq,
dtstart: rule.options.dtstart,
})
;('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;')
RRule.fromString(rfcString)Constructs an RRule instance from a complete rfcString:
var rule = RRule.fromString('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;')
// This is equivalent
var rule = new RRule(
RRule.parseString('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY')
)
RRule.parseString(rfcString)Only parse RFC string and return options.
var options = RRule.parseString('FREQ=DAILY;INTERVAL=6')
options.dtstart = datetime(2000, 2, 1)
var rule = new RRule(options)
These methods provide an incomplete support for text→RRule and
RRule→text conversion. You should test them with your input to see
whether the result is acceptable.
RRule.prototype.toText([gettext, [language]])Returns a textual representation of rule. The gettext callback, if
provided, will be called for each text token and its return value used
instead. The optional language argument is a language definition to be
used (defaults to rrule/nlp.js:ENGLISH).
var rule = new RRule({
freq: RRule.WEEKLY,
count: 23,
})
rule.toText()
;('every week for 23 times')
RRule.prototype.isFullyConvertibleToText()Provides a hint on whether all the options the rule has are convertible to text.
RRule.fromText(text[, language])Constructs an RRule instance from text.
rule = RRule.fromText('every day for 3 times')
RRule.parseText(text[, language])Parse text into options:
options = RRule.parseText('every day for 3 times')
// {freq: 3, count: "3"}
options.dtstart = datetime(2000, 2, 1)
var rule = new RRule(options)
RRuleSet Constructornew RRuleSet([(noCache = false)])
The RRuleSet instance allows more complex recurrence setups, mixing multiple
rules, dates, exclusion rules, and exclusion dates.
Default noCache argument is false, caching of results will be enabled,
improving performance of multiple queries considerably.
RRuleSet.prototype.rrule(rrule)Include the given rrule instance in the recurrence set generation.
RRuleSet.prototype.rdate(dt)Include the given datetime instance dt in the recurrence set generation.
RRuleSet.prototype.exrule(rrule)Include the given rrule instance in the recurrence set exclusion list. Dates
which are part of the given recurrence rules will not be generated, even if
some inclusive rrule or rdate matches them. NOTE: EXRULE has been (deprecated
in RFC 5545)[https://icalendar.org/iCalendar-RFC-5545/a-3-deprecated-features.html]
and does not support a DTSTART property.
RRuleSet.prototype.exdate(dt)Include the given datetime instance dt in the recurrence set exclusion list. Dates
included that way will not be generated, even if some inclusive rrule or
rdate matches them.
RRuleSet.prototype.tzid(tz?)Sets or overrides the timezone identifier. Useful if there are no rrules in this
RRuleSet and thus no DTSTART.
RRuleSet.prototype.all([iterator])Same as RRule.prototype.all.
RRuleSet.prototype.between(after, before, inc=false [, iterator])Same as RRule.prototype.between.
RRuleSet.prototype.before(dt, inc=false)Same as RRule.prototype.before.
RRuleSet.prototype.after(dt, inc=false)Same as RRule.prototype.after.
RRuleSet.prototype.rrules()Get list of included rrules in this recurrence set.
RRuleSet.prototype.exrules()Get list of excluded rrules in this recurrence set.
RRuleSet.prototype.rdates()Get list of included datetimes in this recurrence set.
RRuleSet.prototype.exdates()Get list of excluded datetimes in this recurrence set.
rrulestr Functionrrulestr(rruleStr[, options])
The rrulestr function is a parser for RFC-like syntaxes. The string passed
as parameter may be a multiple line string, a single line string, or just the
RRULE property value.
Additionally, it accepts the following keyword arguments:
cachetrue, the rruleset or rrule created instance
will cache its results.
Default is not to cache.
dtstartDTSTART property is found in the parsed string.
If it is not given, and the property is not found,
datetime.now() will be used instead.
unfoldtrue, lines will be unfolded following the RFC specification.
It defaults to false, meaning that spaces before every line will be stripped.
forcesettrue, an rruleset instance will be returned,
even if only a single rule is found.
The default is to return an rrule if possible, and
an rruleset if necessary.
compatibletrue, the parser will operate in RFC-compatible mode.
Right now it means that unfold will be turned on, and if a DTSTART is found,
it will be considered the first recurrence instance, as documented in the RFC.
tzidTZID
property is found in the parsed string.
If it is not given, and the property is not found, 'UTC' will
be used by default.
RRule has no byday keyword. The equivalent keyword has been replaced by
the byweekday keyword, to remove the ambiguity present in the original
keyword.dtstart, is
not the first recurrence instance, unless it does fit in the specified rules.
This is in part due to this project being a port of
python-dateutil,
which has the same non-compliant functionality. Note that you can get the
original behavior by using a RRuleSet and adding the dtstart as an rdate.var rruleSet = new RRuleSet()
var start = datetime(2012, 2, 1, 10, 30)
// Add a rrule to rruleSet
rruleSet.rrule(
new RRule({
freq: RRule.MONTHLY,
count: 5,
dtstart: start,
})
)
// Add a date to rruleSet
rruleSet.rdate(start)
byweekno is only valid on yearly frequencies, for example.)rrule.js is implemented in Typescript. It uses JavaScript Standard Style coding style.
To run the code, checkout this repository and run:
$ yarn
To run the tests, run:
$ yarn test
To build files for distribution, run:
$ yarn build
Python dateutil is written by Gustavo
Niemeyer.
See LICENCE for more details.
FAQs
JavaScript library for working with recurrence rules for calendar dates.
The npm package rrule receives a total of 475,847 weekly downloads. As such, rrule popularity was classified as popular.
We found that rrule demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST's new password guidelines remove periodic changes and special character requirements, focusing on longer, more secure passwords for better authentication practices.
Security News
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.